String Procedures

This is a collection of assorted, ready-to-use string procedures to manipulate FreeBasic strings and my own DWSTRING (Dynamic Unicode string) and BSTRING (OLE strings, aka BSTR).

The procedures that need to be fast have been hard coded, whereas the ones that need flexibility use CRegExp, a wrapper class on top of the VBScript regular expressions engine.

CRegExp can also be used to build other string procedures not included in this collection.

Include file: AfxNova/DWSTRProcs.inc

Additionally, we can call external variadic functions written in C. They can be very useful to do string formatting.

StringCbPrintf (A/W): https://msdn.microsoft.com/en-us/library/windows/desktop/ms647510(v=vs.85).aspx

DIM wszOut AS WSTRING * 260
DIM wszFmt AS WSTRING * 260 = "%s %d + %d = %d."
DIM wszText AS WSTRING * 260 = "The answer is"
DIM hr AS HRESULT = StringCbPrintfW(@wszOut, SIZEOF(wszOut), @wszFmt, @wszText, 1, 2, 3)
PRINT wszOut
' Output: "The answer is 1 + 2 = 3."

StringCbPrintf_l (A/W) is similar to StringCbPrintf but includes a parameter for locale information.

StringCbPrintfEx (A/W) adds to the functionality of StringCbPrintf by returning a pointer to the end of the destination string as well as the number of bytes left unused in that string. Flags may also be passed to the function for additional control.

StringCbPrintf_lEx (A/W) is similar to StringCbPrintfEx but includes a parameter for locale information.

String procedures list

Surrogates

Checking and fixing broken surrogates is disabled by default for speed reasons. If you want to enable it, use "#define __AFX_CHECKSURROGATES__" (without the quotes) at the beginning of your application, before including the files of this framework. Surrogate checking and fixing is centralized in te internal AppendBuffer method of the DWSTRING class.

Surrogate macros

The wollowing macros are available in the Windows headers (winnls.bi):

const HIGH_SURROGATE_START = &hd800
const HIGH_SURROGATE_END = &hdbff
const LOW_SURROGATE_START = &hdc00
const LOW_SURROGATE_END = &hdfff
#define IS_HIGH_SURROGATE(wch) (((wch) >= HIGH_SURROGATE_START) andalso ((wch) <= HIGH_SURROGATE_END))
#define IS_LOW_SURROGATE(wch) (((wch) >= LOW_SURROGATE_START) andalso ((wch) <= LOW_SURROGATE_END))
#define IS_SURROGATE_PAIR(hs, ls) (IS_HIGH_SURROGATE(hs) andalso IS_LOW_SURROGATE(ls))

IS_HIGH_SURROGATE: Determines if a character is a UTF-16 high surrogate code point, ranging from &hD800 to &hDBFF, inclusive.

IS_LOW_SURROGATE: Determines if a character is a UTF-16 low surrogate code point, ranging from &hDC00 to &hDFFF, inclusive.

IS_SURROGATE_PAIR: Determines if the specified code units form a UTF-16 surrogate pair.

Locale information

DWStrGetUserDefaultLocaleName

Retrieves the user default locale name.

FUNCTION DWStrGetUserDefaultLocaleName () AS DWSTRING

Return value

The user default locale name.

DWStrAcode

Translates Unicode chars to ansi bytes.

FUNCTION DWStrAcode (BYVAL pwszStr AS WSTRING PTR, BYVAL nCodePage AS LONG = 0) AS STRING

Return value

The translated string.

DWStrClip

Returns a string with the specified number of characters removed from the left, middle or right side of the string.

FUNCTION FUNCTION DWStrClip (BYREF wszSide AS CONST WSTRING, BYREF wszSourceString AS CONST WSTRING, _
   BYVAL nCount AS LONG, BYVAL nStart AS LONG = 0) AS DWSTRING

Usage examples

DIM dws AS DWSTRING = DWStrClip("LEFT", "1234567890", 3)     ' Output: "4567890"
DIM dws AS DWSTRING = DWStrClip("RIGHT", "1234567890", 3)    ' Output: "1234567"
DIM dws AS DWSTRING = DWStrClip("MID", "1234567890", 3, 4)   ' Output: "1237890"

DWStrCSet

Returns a string containing a centered (padded) string.

FUNCTION DWStrCSet (BYREF wszSourceString AS CONST WSTRING, BYVAL nStringLength AS LONG, _
   BYREF wszPadCharacter AS CONST WSTRING = " ") AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrCSet("FreeBasic", 20, "*")   ' Output: "*****FreeBasic******"

DWStrCSetAbs

Returns a string containing a centered string within the space of another string.

FUNCTION DWStrCSetAbs (BYREF wszPadString AS CONST WSTRING, BYREF wszString AS CONST WSTRING) AS DWSTRING

Usage example

DIM dwsPad AS DWSTRING = "COOL COOL COOL COOL COOL"
DIM dws AS DWSTRING = "..FreeBasic is.."
PRINT DWStrCSetAbs(dwsPad, dws)
' Output: "COOL..FreeBasic is..COOL"

DWStrDelete

Deletes a specified number of characters from a string expression.

FUNCTION DWStrDelete (BYREF wszSourceString AS CONST WSTRING, BYVAL nStart AS LONG, BYVAL nCount AS LONG) AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrDelete("1234567890", 4, 3)   ' Output: "1237890"

DWStrEnviron

Retrieves the contents of the specified variable from the environment block of the calling process.

FUNCTION DWStrEnviron (BYVAL pwszName AS LPCWSTR) AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrEnviron("path")

DWStrEnvironCount

Returns the number of environment strings-

FUNCTION DWStrEnvironCount () AS LONG

Usage example

DIM count AS Long = DWStrEnvironCount

DWStrEscape

Escapes any potential regex syntax characters in a pattern string and returns a new string that can be safely used as a literal pattern.

FUNCTION DWStrEscape (BYREF wszStr AS CONST WSTRING) AS DWSTRING

DWstrExpandEnvironmentStrings

Expands environment-variable strings and replaces them with the values defined for the current user. To specify the environment block for a particular user or the system, use the Windows API ExpandEnvironmentStringsForUser function.

FUNCTION DWstrExpandEnvironmentStrings (BYREF wszInput AS DWSTRING) AS DWSTRING

Remarks

The size is limited to 32K.

Case is ignored when looking up the environment-variable name. If the name is not found, the %variableName% portion is left unexpanded.

Note that this function does not support all the features that Cmd.exe supports. For example, it does not support %variableName:str1=str2% or %variableName:~offset,length%.

Return value

A unicode string containing the result of expanding the environment variable strings.

DWStrExtract

Extracts characters from a string up to (but not including) a string.

FUNCTION DWStrExtract (BYREF wszSourceString AS CONST WSTRING, BYREF wszMatchString AS CONST WSTRING, _
   BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING
FUNCTION DWStrExtract (BYVAL nStart AS LONG, BYREF wszSourceString AS CONST WSTRING, _
   BYREF wszMatchString AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

nStart is the optional starting position to begin extracting. If nStart is not specified, it will start at position 1. If nStart is zero, or beyond the length of wszSourceString, a nul string is returned. If nStart is negative, the starting position is counted from right to left: if -1, the search begins at the last character; if -2, the second to last, and so forth.

Overloaded methods:

Returns the portion of a string following the occurrence of a specified delimiter up to the second delimiter. If no match is found, an empty string is returned. If nStart is 0 or greater than the length of wszSourceString, an empty string is returned.

FUNCTION DWStrExtract OVERLOAD (BYREF wszSourceString AS CONST WSTRING, BYREF leftDelimiter AS CONST WSTRING, _
   BYREF rightDelimiter AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING
FUNCTION DWStrExtract OVERLOAD (BYVAL nStart AS LONG, BYREF wszSourceString AS CONST WSTRING, _
   BYREF leftDelimiter AS CONST WSTRING, BYREF rightDelimiter AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

Usage examples

DIM dws AS DWSTRING = "abacadabra"
PRINT DWStrExtract(dws, "cad")
' Output: "aba" - match on "cad"

wszMatchStr can specify a list of single characters, enclosed between [], to be searched for individually, a match on any one of which will cause the extract operation to be performed up to that character.

DIM dws AS DWSTRING = "abacadabra"
PRINT DWStrExtract(dws, "[dr]")
' Output: "abaca" - match on "d"

DIM dwsText AS DWSTRING = "blah blah (text between parentheses) blah blah"
PRINT DWStrExtract(dwsText, "(", ")")   ' Output: "text between parentheses"

DWStrFormatByteSize

Converts a numeric value into a string that represents the number expressed as a size value in bytes, kilobytes, megabytes, or gigabytes, depending on the size.

FUNCTION DWStrFormatByteSize (BYVAL ull AS LONGLONG) AS DWSTRING

DWStrFormatKBSize

Converts a numeric value into a string that represents the number expressed as a size value in kilobytes.

FUNCTION DWStrFormatKBSize (BYVAL ull AS LONGLONG) AS DWSTRING

DWStrFromTimeInterval

Converts a time interval, specified in milliseconds, to a string.

FUNCTION DWStrFromTimeInterval (BYVAL dwTimeMS AS DWORD, BYVAL digits AS LONG) AS DWSTRING

Some examples for digits:

DWStrGetEnvironmentStrings

Retrieves the environment variables for the current process.

FUNCTION DWStrGetEnvironmentStrings () AS SAFEARRAY PTR

Return value

Pointer to a SafeArray containing the environment variables for the current process.

Usage example

' Remember to include: #include once "AfxNova/DSAFEARRAY.inc"

DIM dsa AS DSAFEARRAY = DSAFEARRAY(DWStrGetEnvironmentStrings, TRUE)
FOR i AS LONG = dsa.LBound TO dsa.UBOUND
   print dsa.GetStr(i)
NEXT

DWStrInsert

Inserts a string at a specified position within another string expression.

FUNCTION DWStrInsert (BYREF wszSourceString AS CONST WSTRING, BYREF wszInsertString AS CONST WSTRING, _
   BYVAL nPosition AS LONG) AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrInsert("1234567890", "--", 6)

DWStrIsNumeric

Retuns True if the passed string is muneric.

FUNCTION DWStrIsNumeric (BYREF wszSourcestring AS CONST WSTRING) AS BOOLEAN

Example

DWStrIsNumeric("1.2345678901234567e+029")   ' Output: "true"

Explanation of the pattern used: “¹?(?:[Ee][+-]?)?$”

^ ? Anchors the match to the start of the string.
[\+\-]? ? Matches an optional plus (+) or minus (-) sign at the beginning (for signed numbers).
\d* ? Matches zero or more digits before the decimal point (allows integers or leading zero suppression).
\.? ? Matches an optional decimal point (if present, allows floating-point numbers).
\,? ? Matches an optional decimal point (in Spain, a comma is used instead of a colon).
\d+ ? Matches at least one digit after the decimal (ensuring valid numeric values).
(?:[Ee][\+\-]?\d+)? ? Handles scientific notation:
  E or e for exponent notation.
  [\+\-]? for optional sign after the exponent indicator.
  \d+ ensures at least one digit in the exponent.
$ ? Anchors the match to the end of the string, ensuring a full numeric match.

DWStrJoin

Returns a string consisting of all of the strings in an array, each separated by a delimiter. If the delimiter is a null (zero-length) string then no separators are inserted between the string sections. If the delimiter expression is the 3-byte value of ‘“,”’, which may be expressed in your source code as the string literal “““,”“” or as Chr(34,44,34) then a leading and trailing double-quote is added to each string section. This ensures that the returned string contains standard comma-delimited quoted fields that can be easily parsed.

#macro DWStrJoin(array, dest, delim)

Return value

A string containing the joined string.

Usage example

DIM rg(1 TO 10) AS DWSTRING
FOR i AS LONG = 1 TO 10
   rg(i) = "string " & i
NEXT
DIM dws AS DWSTRING
DWStrJoin(rg, dws, """,""")
PRINT dws
' Instead of DWSTRING, any other data type can be used: BSTRING, STRING...

DWStrLCase

Returns a lowercased version of a string.

FUNCTION DWStrLCase (BYVAL pwszStr AS WSTRING PTR, _
   BYVAL pwszLocaleName AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT, _
   BYVAL dwMapFlags AS DWORD = 0) AS DWSTRING

For a table of language culture names see: Table of Language Culture Names, Codes, and ISO Values

For a complete list see: LCMapStringEx function

Remarks

The string conversion functions available in FreeBasic are not fully suitable for some languages. For example, the Turkish word “karışıklığı” is uppercased as “KARıŞıKLıĞı” instead of “KARIŞIKLIĞI”, and “KARIŞIKLIĞI” is lowercased to “karişikliği” instead of “karışıklığı”. Notice the “ı”, that is not an “i”.

For Turkey, use:

DWStrUCase("karışıklığı", "tr-TR")
DWStrLCase("KARIŞIKLIĞI", "tr-TR")

Return value

The lowercased string.

DWStrLSet

Returns a string containing a left justified string.

FUNCTION DWStrLSet (BYREF wszSourceString AS CONST WSTRING, BYVAL nStringLength AS LONG, _
   BYREF wszPadCharacter AS CONST WSTRING = " ") AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrLSet("FreeBasic", 20, "*")

DWStrLSetAbs

Left-aligns a string within the space of another string. If wszStr is empty, the function leaves the padding positions unchanged from their original content, rather than replacing them with spaces as LSET does. If wszStr is longer than wszSourceString, DWStrLSetAbs truncates it from the right until it fits in the result string.

FUNCTION DWStrLSetAbs (BYREF wszSourceString AS CONST WSTRING, BYREF wszStr AS CONST WSTRING) AS DWSTRING

Usage example

DIM dws AS DWSTRING = "NameBasic=SuperBasic"
PRINT DWStrLSetAbs(dws, "FreeBasic")  ' Output: "FreeBasic=SuperBasic"

DWStrMCase

Returns a mixed case version of its string argument.

FUNCTION DWStrMCase (BYREF wszSourceString AS WSTRING) AS DWSTRING

Example

DIM dws AS DWSTRING = strMCase("Cats aren't AL.WAYS good.")
' Output: "Cats Aren'T Al.Ways Good."
' Note: It mimincs PowerBASIC's MCase$ function.

DWStrParse

Returns a delimited field from a string expression.

FUNCTION DWStrParse (BYREF wszSourceString AS CONST WSTRING, BYVAL index AS LONG = 1, _
   BYREF wszDelimiter AS CONST WSTRING = ",") AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrParse("one,two,three")           ' Output: "one"
DIM dws AS DWSTRING = DWStrParse("one;two,three", 1, ";")   ' Output: "one"
DIM dws AS DWSTRING = DWStrParse("1;2,3", 2, ",;")          ' Output: "2"

DWStrParseCount

Returns the count of delimited fields from a string expression.

FUNCTION DWStrParseCount (BYREF wszSourceString AS CONST WSTRING, BYREF wszDelimiter AS CONST WSTRING = ",") AS LONG

Usage example

DIM nCount AS LONG = DWStrParseCount("one,two,three", ",")   ' Output: "3"
DIM nCount AS LONG = DWStrParseCount("1;2,3", ",;")          ' Output: "3"

DWStrPathName

Parses a path to extract component parts.

FUNCTION DWStrPathName (BYREF wszOption AS CONST WSTRING, BYREF wszFileSpec AS WSTRING) AS DWSTRING

DWStrPathScan

Searches a path for a file name.

FUNCTION DWStrPathScan (BYREF wszOption AS CONST WSTRING, BYREF wszFileSpec AS CONST WSTRING,_
   BYREF wszOtherDirs AS CONST WSTRING = "") AS DWSTRING

Return value

If the file is found, it returns either the full path/file name, or a selected part of it.If the file is not found, a null (zero-length) is returned. If you wish to simply parsea text file name, without regard to its validation on disk, you should use the companionfunction DWStrPathName.

DWStrRemain

Returns the portion of a string following the first occurrence of a character or group of characters. If wszMatchString is not present in wszSourceString (or is null) then a zero-length empty string is returned.

FUNCTION DWStrRemain (BYREF wszSourceString AS CONST WSTRING, BYREF wszMatchString AS CONST WSTRING, _
   BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING
FUNCTION DWStrRemain (BYVAL nStart AS LONG, BYREF wszSourceString AS CONST WSTRING, _
   BYREF wszMatchString AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

Usage examples

DIM dws AS DWSTRING = "I think, therefore I am"
dws = DWStrRemain(dws, ",", TRUE)
PRINT dws
' Output: " therefore I am"

DIM dws AS DWSTRING = "One, two, three"
dws = DWStrRemain(5, dws, ",", TRUE)
PRINT dws
' Output: " three"

DWStrRemove

Returns a new string with strings removed.

FUNCTION DWStrRemove (BYREF wszSourceString AS CONST WSTRING, BYREF wszMatchString AS CONST WSTRING, _
   BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING
FUNCTION DWStrRemove (BYVAL nStart AS LONG, BYREF wszSourceString AS CONST WSTRING, _
   BYREF wszMatchString AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

Overloaded methods:

Return a copy of a string with a substring enclosed between the specified delimiters removed.

FUNCTION DWStrRemove (BYREF wszSourceString AS CONST WSTRING, BYREF leftDelimiter AS CONST WSTRING, _
   BYREF rightDelimiter AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING
FUNCTION DWStrRemove OVERLOAD (BYVAL nStart AS LONG, BYREF wszSourceString AS CONST WSTRING, _
   BYREF leftDelimiter AS CONST WSTRING, BYREF rightDelimiter AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

Usage examples

DWStrRemove("Hello World. Welcome to the Freebasic World", "World")   'Output: "Hello . Welcome to the Freebasic"
DWStrRemove("abacadabra", "bac")        ' Output: "aaabra"
DWStrRemove("abacadabra", "[bac]")      ' Output: "dr"

DIM dwsText AS DWSTRING = "As Long var1(34), var2(  73 ), var3(any)"
PRINT DWStrRemove(19, dwsText, "(", ")", TRUE)   ' Returns "var2, var3"

DWStrRemoveEnviron

Removes the specified environment variable from the current process.

FUNCTION DWStrRemoveEnviron (BYVAL pwszName AS LPCWSTR) AS BOOLEAN

Usage example

DWStrRemoveEnviron("TEMP")

Return value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

DWStrRepeat

Returns a string consisting of multiple copies of the specified string. This function is similar to FreeBasic STRING, but STRING only makes multiple copies of a single character.

FUNCTION DWStrRepeat (BYVAL nCount AS LONG, BYREF wszSourceString AS CONST WSTRING) AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrRepeat(5, "Paul")

DWStrReplace

Replaces all the occurrences of wszMatchStr in wszSourceString with the contents of wszReplaceWith.

FUNCTION DWStrReplace (BYREF wszSourceString AS CONST WSTRING, BYREF wszMatchString AS CONST WSTRING, _
   BYREF wszReplaceString AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

Usage examples

DWStrReplace("Hello World", "World", "Earth")   ' Output: "Hello Earth"
DWStrReplace("abacadabra", "bac", "***")        ' Output: "a***adabra"
DWStrReplace("abacadabra", "[bac]", "*")        ' Output: "*****d**r*"

DWStrRetain

Returns a string containing only the characters contained in a specified match string. If wszMatchString is an empty string, strRetain returns an empty string.

FUNCTION DWStrRetain (BYREF wszSourceString AS CONST WSTRING, BYREF wszMatchString AS CONST WSTRING, _
   BYVAL IgnoreCase AS BOOLEAN = TRUE) AS DWSTRING

Usage examples

DIM dws AS DWSTRING = "abacadabra"
dws = DWStrRetain(dws, "B", TRUE)
PRINT dws
' Output: "bb"

DIM dws AS DWSTRING = "<p>1234567890<ak;lk;l>1234567890</p>"
dws = DWStrRetain(dws, "<;/p>", TRUE)
PRINT dws
' Output: "<p><;;></p>"

DIM dws AS DWSTRING = "<p>1234567890<ak;lk;l>1234567890</p>"
dws = DWStrRetain(dws, "0123456789", TRUE)
PRINT dws
' Output: "12345678901234567890"

DWStrReverse

Reverses the contents of a string expression.

FUNCTION DWStrReverse (BYREF wszSourceString AS CONST WSTRING) AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrReverse("garden")   ' Output: "nedrag"

DWStrRSet

Returns a string containing a right justified string.

FUNCTION DWStrRSet (BYREF wszSourceString AS CONST WSTRING, BYVAL nStringLength AS LONG, _
   BYREF wszPadCharacter AS CONST WSTRING = " ") AS DWSTRING

Usage example

DIM dws AS DWSTRING = DWStrRSet("FreeBasic", 20, "*")

DWStrSetEnviron

Sets the contents of the specified environment variable for the current process.

FUNCTION DWStrSetEnviron (BYVAL pwszName AS LPCWSTR, BYVAL pwszValue AS LPCWSTR) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Usage example

DWStrSetEnviron("path", "c:")

DWStrSetEnviron (Overload)

Sets the contents of the specified environment variable for the current process.
Unicode replacement for Free Basic’s SetEnviron function.

FUNCTION DWStrSetEnviron (BYVAL pwszName AS LPCWSTR, BYVAL pwszValue AS LPCWSTR) AS BOOLEAN
FUNCTION DWStrSetEnviron (BYREF varexp AS WSTRING) AS BOOLEAN

Return value

Returns 0 on success, or -1 on failure.

DWStrRSetAbs

Right-aligns a string within the space of another string. If wszStr is empty, the function leaves the padding positions unchanged from their original content, rather than replacing them with spaces as RSET does. If wszStr is longer than wszSourceString, DWStrRSetAbs truncates it from the right until it fits in the result string.

FUNCTION DWStrRSetAbs (BYREF wszSourceString AS CONST WSTRING, BYREF wszStr AS CONST WSTRING) AS DWSTRING

Usage example

DIM dws AS DWSTRING = "NameBasic=NameBasic"
PRINT DWStrRSetAbs(dws, "FreeBasic")  ' Output: "NameBasic=FreeBasic"

DWStrShrink

Shrinks a string to use a consistent single character delimiter.

FUNCTION DWStrShrink(BYREF wszSourceString AS CONST WSTRING, BYREF wszMask AS CONST WSTRING = "", _
   BYVAL IgnoreCase AS LONG = TRUE) AS DWSTRING

Remarks

This function creates a string with consecutive words separated by a consistent single character, making it easier to parse. If wszMask is not specified, all leading and trailing spaces are removed and all occurrences of two or more spaces are changed to a single space. If wszMask contains one or more characters to shrink, all the leading and trailing occurences of them are removes and all occurrences of one or more characters of the mask are replaced with the first character of the mask.

Usage example

DIM dws AS DWSTRING = DWStrShrink(",,, one , two     three, four,", " ,")
' Output: "one two three four".

DWStrSplit

Splits a string into tokens, which are sequences of contiguous characters separated by any of the characters that are part of delimiters. Each token is added to a DWSTRING (my own dynamic Unicode string data type for FreeBasic) and delimited by a carriage return and line feed. The returned string will be parsed later to get the individual tokens.

FUNCTION DWStrSplit (BYREF wszStr AS WSTRING, BYREF wszDelimiters AS WSTRING = " ", _
   BYREF wszSeparator AS WSTRING = CHR(34, 44, 34), BYVAL maxsplits AS LONG = -1) AS DWSTRING

Return value

A list of tokens separated by the optional seoarator specified in wszSeparator.

Usage example

DIM wsz AS WSTRING * 260 = "- This, a sample string."
DIM dwsTokens AS DWSTRING = DWStrSplit(wsz, " ,.-", , -1)
PRINT "len dwsTokens: ", len(dwsTokens)
PRINT dwsTokens
' Output: "This","a","sample","string"
' Passing " # " in wszSeparator:
' DIM dwsTokens AS DWSTRING = DWStrSplit(wsz, " ,.-", " # ", -1)
' Output: "This # a # sample # string"

DWStrSpn

Returns the index of the initial portion of a string which consists only of characters that are part of a specified set of characters.

FUNCTION DWStrSpn (BYREF wszText AS CONST WSTRING, BYREF wszSet AS CONST WSTRING, BYVAL IgnoreCase AS LONG = TRUE) AS LONG

Usage example

DIM dwsText AS DWSTRING = "129th"
DIM dwsSet AS DWSTRING = "1234567890"
DIM n AS LONG = DWStrSpn(dwsText, dwsSet)
PRINT "The initial number has " & WSTR(n) & " digits"   ' Output: "3"

Remarks

The Windows API StrSpnW function and the C wcsspn function can also be used.

DWStrTally

Count the number of occurrences of a string or a list of characters within a string.

FUNCTION DWStrTally (BYREF wszSourceString AS CONST WSTRING, BYREF wszMatchString AS CONST WSTRING, _
   BYVAL IgnoreCase AS BOOLEAN = TRUE) AS LONG

Return value

The number of occurrences of wszMatchStr in wszSourceString.

Usage examples

DIM dws AS DWSTRING = "abacadabra"
DIM nCount AS LONG = DWStrTally(dws, "bac")
PRINT nCount
' Output: Returns 1, counting the string "bac"

DIM dws AS DWSTRING = "abacadabra"
DIM nCount AS LONG = DWStrTally(dws, "b|a|c")   ' // [bac] is the same that [b|a|c]
PRINT nCount
' Output: Returns 8, counting all "b", "a", and "c" characters.
' The | is the OR operator in regular expressions. It means "match b OR a OR c".

DWstrToUtf8

Converts Unicode to utf8.

FUNCTION DWStrToUtf8 (BYVAL pwszStr AS WSTRING PTR) AS STRING

Return value:

The converted unicode string as a utf8 string.

DWstrToOem

Transltes Unicode to OEM byte characters.

FUNCTION DWStrToOem (BYVAL pwszStr AS WSTRING PTR) AS STRING

Return value:

The converted unicode string as an OEM string.

DWStrUCase

Returns an uppercased version of a string.

FUNCTION DWStrUCase (BYVAL pwszStr AS WSTRING PTR, _
   BYVAL pwszLocaleName AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT, _
   BYVAL dwMapFlags AS DWORD = 0) AS DWSTRING

For a table of language culture names see: Table of Language Culture Names, Codes, and ISO Values

For a complete list see: LCMapStringEx function

Remarks

The string conversion functions available in FreeBasic are not fully suitable for some languages. For example, the Turkish word “karışıklığı” is uppercased as “KARıŞıKLıĞı” instead of “KARIŞIKLIĞI”, and “KARIŞIKLIĞI” is lowercased to “karişikliği” instead of “karışıklığı”. Notice the “ı”, that is not an “i”.

For Turkey, use:

DWStrUcase("karışıklığı", "tr-TR")
DWStrLCase("KARIŞIKLIĞI", "tr-TR")

Return value

The uppercased string.

DWStrUCode

Translates ansi bytes to Unicode chars.

FUNCTION DWStrUCode (BYREF ansiStr AS CONST STRING, BYVAL nCodePage AS LONG = 0) AS DWSTRING

Return value

The translated string.

DWStrUnWrap

Removes paired characters to the beginning and end of a string.

FUNCTION DWStrUnWrap (BYREF wszSourceString AS CONST WSTRING, BYREF wszLeftChar AS CONST WSTRING, _
   BYREF wszRightChar AS CONST WSTRING) AS DWSTRING

FUNCTION DWStrUnWrap (BYREF wszSourceString AS CONST WSTRING, BYREF wszChar AS CONST WSTRING = CHR(34)) AS DWSTRING

Remarks

If only one wrap character/string is specified then that character or string is used for both sides. If no wrap character/string is specified then double quotes are used.

Usage examples

DWStrUnWrap("<Paul>", "<", ">") results in Paul
DWStrUnWrap("'Paul'", "'") results in Paul
DWStrUnWrap("""Paul""") results in Paul

DWStrVerify

Determine whether each character of a string is present in another string.

FUNCTION DWStrVerify (BYVAL nStart AS LONG, BYREF wszSourceString AS CONST WSTRING, _
   BYREF wszMatchString AS CONST WSTRING, BYVAL IgnoreCase AS BOOLEAN = TRUE) AS LONG

Return value

Returns zero if each character in wszSourceString is present in wszMatchStr; otherwise, it returns the position of the first non-matching character in wszSourceString. If nStart is zero, a negative number of a value greater that the length of wszSourceString, zero is returned.

Usage example

DIM dws AS DWSTRING = "123.65,22.5"
DIM nPos AS LONG = DWStrVerify(5, dws, "0123456789", TRUE)
PRINT nPos
' Output: "7"
' Returns "7" since 5 starts it past the first non-digit ("." at position 4)

DWStrWrap

Adds paired characters to the beginning and end of a string.

FUNCTION DWStrWrap (BYREF wszSourceString AS CONST WSTRING, BYREF wszLeftChar AS CONST WSTRING, _
   BYREF wszRightChar AS CONST WSTRING) AS DWSTRING

FUNCTION DWStrWrap (BYREF wszSourceString AS CONST WSTRING, BYREF wszChar AS CONST WSTRING = CHR(34)) AS DWSTRING

Remarks

If only one wrap character/string is specified then that character or string is used for both sides. If no wrap character/string is specified then double quotes are used.

Usage examples

DWStrWrap("Paul", "<", ">") results in <Paul>
DWStrWrap("Paul", "'") results in 'Paul'
DWStrWrap("Paul") results in "Paul"

DWStrBase64DecodeA

Converts the contents of a Base64 mime encoded string to an ascii string.

FUNCTION DWStrBase64DecodeA (BYREF strData AS STRING) AS STRING

Return value

The decoded string on success, or a null string on failure.

Remaks

Base64 is a group of similar encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The Base64 term originates from a specific MIME content transfer encoding.

Base64 encoding schemes are commonly used when there is a need to encode binary data that needs be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is used commonly in a number of applications including email via MIME, and storing complex data in XML.

If we want to encode a unicode string, we must convert it to utf8 before calling AfxBase64EncodeA, e.g.

DIM dws AS DWSTRING = "おはようございます – Good morning!"
DIM s AS STRING = DWStrBase64EncodeA(dws.Utf8)

To decode it, we can use

DIM dwsOut AS dwsTRING = DWSTRING(DWStrBase64DecodeA(s), CP_UTF8)

or

DIM dwsOut AS DWSTRING
dws.utf8 = DWStrBase64DecodeA(s)

DWStrBase64DecodeW

Converts the contents of a Base64 mime encoded string to an unicode string.

FUNCTION DWStrBase64DecodeW (BYREF dwsData AS DWSTRING) AS DWSTRING

Return value

The decoded string on success, or a null string on failure.

Remaks

Base64 is a group of similar encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The Base64 term originates from a specific MIME content transfer encoding.

Base64 encoding schemes are commonly used when there is a need to encode binary data that needs be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is used commonly in a number of applications including email via MIME, and storing complex data in XML.

DWStrBase64EncodeA

Converts the contents of an ascii string to Base64 mime encoding.

FUNCTION DEStrBase64EncodeA (BYREF strData AS STRING) AS STRING

Return value

The encoded string on succeess, or a null string on failure.

Remarks

Base64 is a group of similar encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The Base64 term originates from a specific MIME content transfer encoding.

Base64 encoding schemes are commonly used when there is a need to encode binary data that needs be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is used commonly in a number of applications including email via MIME, and storing complex data in XML.

If we want to encode a unicode string, we must convert it to utf8 before calling AfxBase64Encode, e.g.

DIM dws AS DWSTRING = "おはようございます – Good morning!"
DIM s AS STRING = DWStrBase64EncodeA(dws.Utf8)

To decode it, we can use

DIM dwsOut AS DWSTRING = DWSTRING(DWStrBase64DecodeA(s), CP_UTF8)

or

DIM dwsOut AS DWSTRING
dws.utf8 = DWStrBase64DecodeA(s)

DWStrBase64EncodeW

Converts the contents of an unicode string to Base64 mime encoding.

FUNCTION DWStrBase64EncodWeA (BYREF dwsData AS DWSTRING) AS DWSTRING

Return value

The encoded string on succeess, or a null string on failure.

Remarks

Base64 is a group of similar encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The Base64 term originates from a specific MIME content transfer encoding.

Base64 encoding schemes are commonly used when there is a need to encode binary data that needs be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is used commonly in a number of applications including email via MIME, and storing complex data in XML.

DWStrCryptBinaryToString

Converts an array of bytes into a formatted string.

FUNCTION FUNCTION DWStrCryptBinaryToStringA ( _
   BYVAL pbBinary AS CONST UBYTE PTR, _
   BYVAL cbBinary AS DWORD, _
   BYVAL dwFlags AS DWORD, _
   BYVAL pszString AS LPSTR, _
   BYVAL pcchString AS DWORD PTR _
) AS WINBOOL

FUNCTION DWStrCryptBinaryToStringW ( _
   BYVAL pbBinary AS CONST UBYTE PTR, _
   BYVAL cbBinary AS DWORD, _
   BYVAL dwFlags AS DWORD, _
   BYVAL pszString AS LPWSTR, _
   BYVAL pcchString AS DWORD PTR _
) AS WINBOOL

Values available for the dwFlags parameter:

In addition to the values above, one or more of the following values can be specified to modify the behavior of the function.

Return value

If the function succeeds, the function returns nonzero (CTRUE). If the function fails, it returns zero (FALSE).

Remarks

With the exception of when CRYPT_STRING_BINARY encoding is used, all strings are appended with a new line sequence. By default, the new line sequence is a CR/LF pair (0x0D/0x0A). If the dwFlags parameter contains the CRYPT_STRING_NOCR flag, then the new line sequence is a LF character (0x0A). If the dwFlags parameter contains the CRYPT_STRING_NOCRLF flag, then no new line sequence is appended to the string.

DWStrCryptStringToBinary

Converts a formatted string into an array of bytes.

FUNCTION DWStrCryptStringToBinaryA ( _
   BYVAL pszString AS LPCSTR, _
   BYVAL cchString AS DWORD, _
   BYVAL dwFlags AS DWORD, _
   BYVAL pbBinary AS UBYTE PTR, _
   BYVAL pcbBinary AS DWORD PTR, _
   BYVAL pdwSkip AS DWORD PTR, _
   BYVAL pdwFlags AS DWORD PTR _
) AS WINBOOL

FUNCTION DWStrCryptStringToBinaryW ( _
   BYVAL pszString AS LPCWSTR, _
   BYVAL cchString AS DWORD, _
   BYVAL dwFlags AS DWORD, _
   BYVAL pbBinary AS UBYTE PTR, _
   BYVAL pcbBinary AS DWORD PTR, _
   BYVAL pdwSkip AS DWORD PTR, _
   BYVAL pdwFlags AS DWORD PTR _
) AS WINBOOL

Values available for the dwFlags parameter:

Values available for the pdwFlags parameter:

DWStrHasSurrogates

Checks if the specified string has surrogates.

FUNCTION DWStrHasSurrogates (BYREF wszStr AS WSTRING) AS BOOLEAN

Return value

BOOLEAN. True if the string has rurrogates; False, otherwise.

DWStrIsValidSurrogatePair

Checks whether a UTF-16 encoded string contains valid high-low surrogate pairs.

FUNCTION DWStrIsValidSurrogatePair (BYVAL high AS USHORT, BYVAL low AS USHORT) AS BOOLEAN

Return value

BOOLEAN. True if the surrogate pair is valid; False, otherwise.

DWStrSurrogatePairToCodePoint

Converts a surrogate pair to a Unicode code point.

FUNCTION DWStrSurrogatePairToCodePoint (BYVAL high AS USHORT, BYVAL low AS USHORT) AS ULONG

Return value

BOOLEAN. True if the surrogate pair is valid; False, otherwise.

DWStrCodePointToSurrogatePair

Converts a Unicode code point (above U+FFFF) back into its high and low surrogate pair.

SUB DWStrCodePointToSurrogatePair (BYVAL codePoint AS ULONG, BYREF high AS USHORT, BYREF low AS USHORT)

Return value

This method does not return a value.

DWStrScanForSurrogates

Scans a UTF-16 buffer (passed as a pointer to WSTRING) in chunks of 64 characters. Returns the 0-based index (relative to memAddr) of the first broken surrogate found, or -1 if none is found.

FUNCTION DWStrScanForSurrogates( _
   BYVAL memAddr AS WSTRING PTR, _
   BYVAL nChars AS LONG, _
   BYVAL searchBrokenOnly AS BOOLEAN = TRUE) AS LONG

Result code

Returns the 0-based index (relative to memAddr) of the first broken surrogate found, or -1 if none is found. If the optional parameter searchBrokenOnly is set to false, then it returns the 0-based index of the first surroghate found, broken or not.

DWStrChrW

Returns a wide-character string from a codepoint.

FUNCTION DWStrChrW (BYVAL codepoint AS UInteger) AS DWSTRING
   If codepoint <= &hFFFF Then RETURN WCHR(codepoint)
   ' Convert to UTF-16 surrogate pair for higher codepoints
   DIM AS USHORT highSurrogate = &hD800 OR ((codepoint - &h10000) SHR 10)
   DIM AS USHORT lowSurrogate = &hDC00 OR ((codepoint - &h10000) AND &h3FF)
   RETURN WCHR(highSurrogate) + WCHR(lowSurrogate)
END FUNCTION

Return value

The codepoint returned is the sum of a surrogate pair.

DWStrAbbrevDayName

Returns the abbreviated native day name for the specified day (1 = Monday, etc.).

FUNCTION DWStrAbbrevDayName (BYVAL nDay AS LONG, BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrAbbrevMonthName

Returns the abbreviated native day name for the specified month (1 to 12).

FUNCTION DWStrAbbrevMonthName (BYVAL nMonth AS LONG, BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrCountryName

Returns the fuññ localized name of the country/region.

FUNCTION DWStrCountryName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrCurrencySymbol

String used as the local monetary symbol. The maximum number of characters allowed for this string is 13, including a terminating null character. For example, in the United States, this symbol is “$”.

FUNCTION DWStrCurrencySymbol (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrDateSeparator

Character(s) for the date separator. The maximum number of characters allowed for this string is four, including a terminating null character. This constant is deprecated. A custom locale might not have a single, uniform separator character. For example, a format such as “12/31, 2006” is valid. See DwstrShortDateFormatString.

FUNCTION DWStrDateSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrDayName

Returns the native day name for the specified day (1 = Monday, etc.).

FUNCTION DWStrDateSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrDecimalSeparator

Character(s) used for the decimal separator, for example, “.” in “3.14” or “,” in “3,14”. The maximum number of characters allowed for this string is four, including a terminating null character.

FUNCTION DWStrDecimalSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrDigitsGrouping

Sizes for each group of digits to the left of the decimal. The maximum number of characters allowed for this string is ten, including a terminating null character. An explicit size is needed for each group, and sizes are separated by semicolons. If the last value is 0, the preceding value is repeated. For example, to group thousands, specify 3;0. Indic locales group the first thousand and then group by hundreds. For example, 12,34,56,789 is represented by 3;2;0.

FUNCTION DWStrDigitsGrouping (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrDisplayName

Primary language name included in a localized display name. Deprecated. See DWStrLocalizedDisplayName.

FUNCTION DWStrDisplayName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrEnglishCountryName

Full English name of the country/region.

FUNCTION DWStrEnglishCountryName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrEnglishCurrencyName

The full English name of the currency associated with the locale.

FUNCTION DWStrEnglishCurrencyName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrEnglishDisplayName

Display name of the locale in English. Usually the display name consists of the language and the country/region, for example, German (Germany) for Deutsch (Deutschland).

FUNCTION DWStrEnglishDisplayName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrEnglishLanguageName

Full English name of the language from ISO Standard 639.

FUNCTION DWStrEnglishLanguageName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrInternationalMonetarySymbol

Three characters of the international monetary symbol specified in ISO 4217, followed by the character separating this string from the amount. The maximum number of characters allowed for this string is nine, including a terminating null character.

FUNCTION DWStrInternationalMonetarySymbol (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrISO639LanguageName

The abbreviated name of the language based entirely on the ISO Standard 639 values, in lowercase form, for example, “en” for English. The maximum number of characters allowed for this string is nine, including a terminating null character.

FUNCTION DWStrISO639LanguageName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrISO639LanguageName2

Three-letter ISO language name, in lowercase form (ISO 639-2 three-letter code for the language), for example, “eng” for English. The maximum number of characters allowed for this string is nine, including a terminating null character.

FUNCTION DWStrISO639LanguageName2 (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrISO3166CountryName

Country/region name, based on ISO Standard 3166, for example, “US” for the United States. The maximum number of characters allowed for this string is nine, including a terminating null character.

FUNCTION DWStrISO3166CountryName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrISO3166CountryName2

Three-letter ISO region name (ISO 3166 three-letter code for the country/region), for example, “USA” for the United States. The maximum number of characters allowed for this string is nine, including a terminating null character.

FUNCTION DWStrISO3166CountryName2 (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrLanguageName

Full localized name of the language. Deprecated. See DwstrLocalizedLanguageName.

FUNCTION DWStrISO3166CountryName2 (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrListItemsSeparator

Character(s) used to separate list items, for example, a comma is used in many locales. The maximum number of characters allowed for this string is four, including a terminating null character.

FUNCTION DWStrListItemsSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrLocaleName

Locale name, a multi-part tag to uniquely identify the locale. The maximum number of characters allowed for this string is 85, including a terminating null character. The tag is based on the language tagging conventions of RFC 4646.

FUNCTION DWStrLocaleName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrLocalizedCountryName

Full localized name of the country/region, for example, Deutschland for Germany. The maximum number of characters allowed for this string is 80, including a terminating null character. Since this name is based on the localization of the product, it changes for each localized version.

FUNCTION DWStrLocalizedCountryName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrLocalizedDisplayName

Windows 7 and later: Full localized name of the locale for the user interface language, for example, Deutsch (Deutschland) for German (Germany)” There is no limit on the number of characters allowed for this string. Since this name is based on the localization of the product, it changes for each localized version.

FUNCTION DWStrLocalizedDisplayName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrLocalizedLanguageName

Full localized primary name of the user interface language included in a localized display name, for example, Deutsch representing German. Since this name is based on the localization of the product, it changes for each localized version.

FUNCTION DWStrLocalizedLanguageName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrLongDateFormatString

Long date formatting string for the locale. The maximum number of characters allowed for this string is 80, including a terminating null character. The string can consist of a combination of day, month, year, and era format pictures and any string of characters enclosed in single quotes. Characters in single quotes remain as specified. For example, the Spanish (Spain) long date is “dddd, dd’ de ‘MMMM’ de ’yyyy”. Locales can define multiple long date formats.

FUNCTION DWStrLongDateFormatString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrMonetaryDecimalSeparator

Character(s) used as the monetary decimal separator. The maximum number of characters allowed for this string is four, including a terminating null character. For example, if a monetary amount is displayed as “$3.40”, just as “three dollars and forty cents” is displayed in the United States, then the monetary decimal separator is “.”.

FUNCTION DWStrMonetaryDecimalSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrMonetaryGrouping

Sizes for each group of monetary digits to the left of the decimal. The maximum number of characters allowed for this string is ten, including a terminating null character. An explicit size is needed for each group, and sizes are separated by semicolons. If the last value is 0, the preceding value is repeated. For example, to group thousands, specify 3;0. Indic languages group the first thousand and then group by hundreds. For example 12,34,56,789 is represented by 3;2;0.

FUNCTION DWStrMonetaryGrouping (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrMonetaryThousandsSeparator

Character(s) used as the monetary separator between groups of digits to the left of the decimal. The maximum number of characters allowed for this string is four, including a terminating null character. Typically, the groups represent thousands. However, depending on the value specified for LOCALE_SMONGROUPING, they can represent something else.

FUNCTION DWStrMonetaryThousandsSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrMonthDayFormatString

Format string for displaying only the month and the day. The formatting is similar to that defined for LOCALE_SLONGDATE. For example, if the month/day pattern is the full month name followed by the day number with leading zeros, as in “September 03”, the format string is “MMMM dd”. The string can consist of a combination of day and month format pictures and any string of characters enclosed in single quotes. Characters in single quotes remain as specified, for example, ‘de’ for Spanish (Spain). A locale can specify only one month/day format.

DUNCTION DWStrMonthDayFormatString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrMonthName

Returns the native month name for the specified month.

FUNCTION DWStrMonthName (BYVAL nMonth AS LONG, BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNanString

String value for “Not a number”, for example, “Nan” for the English (United States) locale. There is no limit on the number of characters allowed for this string.

FUNCTION DWStrNanString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNativeCountryName

Native name of the country/region, for example, España for Spain. The maximum number of characters allowed for this string is 80, including a terminating null character.

FUNCTION DWStrNativeCountryName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNativeCurrencyName

The native name of the currency associated with the locale, in the native language of the locale. There is no limit on the number of characters allowed for this string.

FUNCTION DWStrNativeCurrencyName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNativeDigits

Native equivalents of ASCII 0 through 9. The maximum number of characters allowed for this string is eleven, including a terminating null character.

FUNCTION DWStrNativeDigits (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNativeDisplayName

Display name of the locale in its native language, for example, Deutsch (Deutschland) for the locale German (Germany).

FUNCTION DWStrNativeDisplayName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNativeLanguageName

Native name of the language. The maximum number of characters allowed for this string is 80, including a terminating null character.

FUNCTION DWStrNativeLanguageName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNegativeInfinityString

String value for “negative infinity”, for example, “-Infinity” for the English (United States) locale. There is no limit on the number of characters allowed for this string.

FUNCTION DWStrNegativeInfinityString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrNegativeSign

String value for the negative sign, for example, “-” for the English (United States) locale. The maximum number of characters allowed for this string is five, including a terminating null character.

FUNCTION DWStrNegativeSign (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrOpenTypeLanguageTag

OpenType language tag used to retrieve culturally appropriate typographic features from a font.

FUNCTION DWStrNegativeSign (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrPermilleSymbol

Symbol used to indicate the permille (U+2030) symbol, that is, ‰.

FUNCTION DWStrPermilleSymbol (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrPositiveInfinityString

Windows Vista and later: String value for “positive infinity”, for example, “Infinity” for the English (United States) locale. There is no limit on the number of characters allowed for the string.

FUNCTION DWStrPositiveInfinityString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrPositiveSign

String value for the positive sign, for example, “+” for the English (United States) locale. The maximum number of characters allowed for this string is five, including a terminating null character.

FUNCTION DWStrPositiveInfinityString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrScriptsList

A string representing a list of scripts, using the 4-character notation used in ISO 15924. Each script name consists of four Latin characters and the list is arranged in alphabetical order with each name, including the last, followed by a semicolon.

FUNCTION DWStrScriptsList (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrShortDateFormatString

Short date formatting string for the locale. The maximum number of characters allowed for this string is 80, including a terminating null character. The string can consist of a combination of day, month, year, and era format pictures. For example, “M/d/yyyy” indicates that September 3, 2004 is written 9/3/2004.

FUNCTION DWStrShortDateFormatString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrShortestDayName

Short native name of the specified day of the week.

FUNCTION DWStrShortestDayName (BYVAL nDay AS LONG, BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrShortTimeFormatString

Short time formatting string for the locale. Patterns are typically derived by removing the “ss” (seconds) value from the long time format pattern. For example, if the long time format is “h:mm:ss tt”, the short time format is most likely “h:mm tt”. This constant can specify multiple formats in a semicolon-delimited list. However, the preferred short time format should be the first value listed.

FUNCTION DWStrShortTimeFormatString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrSortLocale

Name of the locale to use for sorting or casing behavior.

FUNCTION DWStrSortLocale (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrSortName

The full localized name of the sort for the specified locale identifier, dependent on the language of the shell. This constant is used to determine casing and sorting behavior.

FUNCTION DWStrSortName (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrThousandsSeparator

Characters that are used to separate groups of digits to the left of the decimal. The maximum number of characters allowed for this string is four, including a terminating null character. Typically, these groups represent thousands. However, depending on the value specified for LOCALE_SGROUPING, they can represent something else.

FUNCTION DWStrThousandsSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrTimeFormatString

Time formatting strings for the locale. The maximum number of characters allowed for this string is 80, including a terminating null character. The string can consist of a combination of hour, minute, and second format pictures.

FUNCTION DWStrTimeFormatString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrTimeSeparator

Character(s) for the time separator. The maximum number of characters allowed for this string is four, including a terminating null character.

FUNCTION DWStrTimeSeparator (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

DWStrYearMonthFormatString

The year-month formatting string for the locale. The maximum number of characters allowed for this string is 80, including a terminating null character. This string shows the proper format for a date string that contains only the year and the month, using format pictures as defined in Day, Month, Year, and Era Format Pictures.

FUNCTION DWStrYearMonthFormatString (BYVAL pwszLocale AS WSTRING PTR = LOCALE_NAME_USER_DEFAULT) AS DWSTRING

OemToDWStr

Traslates a byte string of OEM characters to Unicode.

FUNCTION OemToDwstr (BYREF oemStr AS CONST STRING) AS DWSTRING

Return value:

The converted OEM string as a DWSTRING.

Utf8ToDWStr

Converts utf8 tp Unicode.

FUNCTION Utf8ToDwstr (BYREF utf8Str AS CONST STRING) AS DWSTRING

Return value:

The converted utf8 string as a DWSTRING.